package org.msb.accentis.data;

import org.msb.accentis.data.pojo.BaseObject;

/**
 * The {@code IObjectListener} interface specifies the contract between the {@link ObjectNotifier} object and objects that wish to be notified of modifications
 * made to instances of {@link BaseObject} objects.
 * 
 * The interface consists of one interrogation method: {@link #listensToClass(Class)} and four notification methods: create, removed, saved, and refreshed. When
 * any {@link BaseObject} instance, managed by the {@link IDataManager} object is modified, the {@link ObjectNotifier} object will call the interrogation method
 * on every registered {code IObjectListener} instance to determine if it is interested in this class of object. If it is, indicated by the interrogation method
 * returning the value {@code true}, the appropriate notification method will be called.
 * 
 * @author Marc Boudreau
 * 
 * @since 0.6.0
 */
public interface IObjectListener {

	/**
	 * The interrogation method used by the {@link ObjectNotifier} to determine if the appropriate notification method should be called on this object.
	 * 
	 * @param klass
	 *            A {@link Class} instance representing the class of the modified object, for which notifications are being dispatched.
	 * 
	 * @return A {@code boolean} value indicating if this instance is interested in notifications for this type of object.
	 */
	boolean listensToClass(Class<? extends BaseObject> klass);

	/**
	 * The notification method for the creation, within the persistence store, of an object.
	 * 
	 * @param object
	 *            The object of some type derived from the {@link BaseObject} class.
	 */
	<T extends BaseObject> void objectCreated(T object);

	/**
	 * The notification method for the removal, from the persistence store, of an object.
	 * 
	 * @param object
	 *            The object of some type derived from the {@link BaseObject} class.
	 */
	<T extends BaseObject> void objectRemoved(T object);

	/**
	 * The notification method for the update, within the persistence store, of an object.
	 * 
	 * @param object
	 *            The object of some type derived from the {@link BaseObject} class.
	 */
	<T extends BaseObject> void objectSaved(T object);

	/**
	 * The notification method for the refreshing, from the persistence store, of an object.
	 * 
	 * @param object
	 *            The object of some type derived from the {@link BaseObject} class.
	 */
	<T extends BaseObject> void objectRefreshed(T object);
}
